
{***********************************************************}
{                                                           }
{      Informix esql "locator.h"                            }
{                                                           }
{      Translated to Object Pascal by                       }
{      Copyright (c) 2001-2008 Luxena Software Company      }
{      http://www.luxena.com                                }
{      e-mail: support@luxena.com                           }
{                                                           }
{***********************************************************}

unit IfxLocator;

{$I lx.inc}

{$IFDEF VER140_OR_ABOVE}
  {$ALIGN 8}
{$ENDIF}

interface

uses
  IfxTypes, IfxStubUnit;


const
  // Enumeration literals for loc_loctype

  LOCMEMORY = 1;                                  // memory storage
  LOCFNAME = 2;                                   // File storage with file name
  LOCFILE = 3;                                    // File storage with fd
  LOCUSER = 4;                                    // User define functions


  // passed to loc_open and stored in loc_oflags

  LOC_RONLY = $1;                                 // read only
  LOC_WONLY = $2;                                 // write only


  // LOC_APPEND can be set when the locator is created
  // if the file is to be appended to instead of created

  LOC_APPEND = $4;                                // write with append
  LOC_TEMPFILE = $8;                              // 4GL tempfile blob


  // LOC_USEALL can be set to force the maximum size of the blob to always be
  // used when the blob is an input source.  This is the same as setting the
  // loc_size field to -1.  Good for LOCFILE or LOCFNAME blobs only.

  LOC_USEALL = $10;                               // ignore loc_size field
  LOC_DESCRIPTOR = $20;                           // BLOB is optical descriptor


  // passed to loc_open and stored in loc_mflags
  LOC_ALLOC = $1;                                 // free and alloc memory


  // Flags to indicate if file is on the server or client
  LO_CLIENT_FILE = $00000000;
  LO_SERVER_FILE = $10000000;

  //*******************************************************************************
  // File open flags used for operating system file open via
  //      - ifx_lo_copy_to_lo
  //      - ifx_lo_copy_to_file
  //      - ifx_file_to_file
  //
  // ******************************************************************************/

  LO_O_EXCL = $00000001;                          // fail if file exists
  LO_O_APPEND = $00000002;                        // append to end of file
  LO_O_TRUNC = $00000004;                         // turncate to 0 if file exists
  LO_O_RDWR = $00000008;                          // read/write (default)
  LO_O_RDONLY = $00000010;                        // read-only (from-flags only)
  LO_O_WRONLY = $00000020;                        // write-only (to-flags only)
  LO_O_BINARY = $00000040;                        // binary-mode (default)
  LO_O_TEXT = $00000080;                          // text-mode (default off)


  //*******************************************************************************
  // Smartblob Definitions
  // ******************************************************************************/

  //******************************************************************************
  // Open flags: see ESQL/C documentation for further explanation.
  //
  // LO_APPEND - Positions the seek position to end-of-file + 1. Affects write
  // operations. Reads can still seek anywhere in the LO. Writes always append.
  //
  // LO_SEQUENTIAL - If set overrides optimizer decision. Indicates that
  // reads are sequential in either forward or reverse direction.
  //
  // LO_RANDOM - If set overrides optimizer decision. Indicates that I/O is
  // random and that the system should not read-ahead.
  // LO_FORWARD - Only used for sequential access. Indicates that the sequential
  // access will be in a forward direction, i.e. from low offset to higher offset.
  // LO_REVERSE - Only used for sequential access. Indicates that the sequential
  // access will be in a reverse direction.
  //
  // LO_BUFFER - If set overrides optimizer decision. I/O goes through the
  // buffer pool.
  //
  // LO_NOBUFFER - If set then I/O does not use the buffer pool.
  // ******************************************************************************/

  LO_APPEND = $1;
  LO_WRONLY = $2;
  LO_RDONLY = $4;                                 // default
  LO_RDWR = $8;
  LO_DIRTY_READ = $10;

  LO_RANDOM = $20;                                // default is determined by optimizer
  LO_SEQUENTIAL = $40;                            // default is determined by optimizer

  LO_FORWARD = $80;                               // default
  LO_REVERSE = $100;

  LO_BUFFER = $200;                               // default is determined by optimizer
  LO_NOBUFFER = $400;                             // default is determined by optimizer
  LO_NODIRTY_READ = $800;

  LO_LOCKALL = $1000;                             // default
  LO_LOCKRANGE = $2000;


{$IFDEF REMOVE_VECTORIO}
  LO_VECTORIO = $4000;
{$ENDIF}


  //  Another set of open flags are defined to make the flags more meaningful

  LO_OPEN_APPEND = LO_APPEND;
  LO_OPEN_WRONLY = LO_WRONLY;
  LO_OPEN_RDONLY = LO_RDONLY;                     // default
  LO_OPEN_RDWR = LO_RDWR;
  LO_OPEN_DIRTY_READ = LO_DIRTY_READ;

  LO_OPEN_RANDOM = LO_RANDOM;                     // default is determined by optimizer
  LO_OPEN_SEQUENTIAL = LO_SEQUENTIAL;             // default is determined by optimizer

  LO_OPEN_FORWARD = LO_FORWARD;                   // default
  LO_OPEN_REVERSE = LO_REVERSE;

  LO_OPEN_BUFFER = LO_BUFFER;                     // default is determined by optimizer
  LO_OPEN_NOBUFFER = LO_NOBUFFER;                 // default is determined by optimizer
  LO_OPEN_NODIRTY_READ = LO_NODIRTY_READ;

  LO_OPEN_LOCKALL = LO_LOCKALL;                   // default
  LO_OPEN_LOCKRANGE = LO_LOCKRANGE;


  // When setting the MI_LO_NOBUFFER flag for write operations, please
  // don't set this flag if the object is small. It usually causes a synchronous
  // flush of the log and a synchronous flush of pages written - this is
  // very slow. Instead use buffered I/O for small writes.

  LO_NOBUFFER_SIZE_THRESHOLD = 8080;

  // see Informix internal use file /vobs/tristarp/incl/sblob.h for other flags

  //*******************************************************************************
  // LO create-time flags:
  //
  // Bitmask - Set/Get via ifx_lo_specset_flags() on ifx_lo_create_spec_t.
  //
  // New applications should use the flags which begin LO_ATTR_
  // The second set of flags are defined for backward compatibility only.
  // ******************************************************************************

  LO_ATTR_LOG = $0001;
  LO_ATTR_NOLOG = $0002;
  LO_ATTR_DELAY_LOG = $0004;
  LO_ATTR_KEEP_LASTACCESS_TIME = $0008;
  LO_ATTR_NOKEEP_LASTACCESS_TIME = $0010;
  LO_ATTR_HIGH_INTEG = $0020;
  LO_ATTR_MODERATE_INTEG = $0040;
  LO_ATTR_TEMP = $0080;

  // these 7 values are defined for backward compatibility only
  LO_LOG = $0001;
  LO_NOLOG = $0002;
  LO_DELAY_LOG = $0004;
  LO_KEEP_LASTACCESS_TIME = $0008;
  LO_NOKEEP_LASTACCESS_TIME = $0010;
  LO_HIGH_INTEG = $0020;
  LO_MODERATE_INTEG = $0040;
  LO_TEMP = $0080;

  // these flags are defined to make the create flags more meaningful
  LO_CREATE_LOG = $0001;
  LO_CREATE_NOLOG = $0002;
  LO_CREATE_DELAY_LOG = $0004;
  LO_CREATE_KEEP_LASTACCESS_TIME = $0008;
  LO_CREATE_NOKEEP_LASTACCESS_TIME = $0010;
  LO_CREATE_HIGH_INTEG = $0020;
  LO_CREATE_MODERATE_INTEG = $0040;
  LO_CREATE_TEMP = $0080;


  //******************************************************************************
  //  Symbolic constants for the "lseek" routine
  //******************************************************************************

  LO_SEEK_SET = 0;                                // Set curr. pos. to "offset"
  LO_SEEK_CUR = 1;                                // Set curr. pos. to current + "offset"
  LO_SEEK_END = 2;                                // Set curr. pos. to EOF + "offset"


  //******************************************************************************
  //  Symbolic constants for lo_lock and lo_unlock routines.
  //******************************************************************************

  LO_SHARED_MODE = 1;                             // ISSLOCK
  LO_EXCLUSIVE_MODE = 2;                          // ISXLOCK

  LO_MAX_END = -1;
  LO_CURRENT_END = -2;


  SB_LOCSIZE = 72;                                // length of TIfx_lo


type

  {  Locators are used to store TEXT or BYTE fields (blobs) in ESQL
     programs.  The "loc_t" structure is described below.  Fields denoted
     USER should be set by the user program and will be examined by the DBMS
     system.  Those denoted SYSTEM are set by the system and may be examined
     by the user program.  Those denoted INTERNAL contain data only the
     system manupilates and examines.

     If "loc_loctype" is set to LOCMEMORY, then the blob is stored in
     primary memory.  The memory buffer is pointed to by the variant
     "loc_buffer".  The field "loc_bufsize" gives the size of "loc_buffer".
     If the "loc_bufsize" is set to "-1" and "loc_mflags" is set to "0"
     and the locator is used for a fetch, memory is obtained using "malloc"
     and "loc_buffer" and "loc_bufsize" are set.

     If "loc_loctype" is set to LOCFILE, then the blob is stored in a file.
     The file descriptor of an open operating system file is specified in
     "loc_fd".

     If "loc_loctype" is set to LOCFNAME, the the blob is stored in a file
     and the name of the file is given.  The DBMS will open or created the
     file at the correct time and in the correct mode.

     If the "loc_loctype" is set to LOCUSER, "loc_(open/close/read/write)"
     are called.  If the blob is an input to a SQL statement, "loc_open" is
     called with the parameter "LOC_RONLY".  If the blob is an output target
     for an SQL statement, "loc_open" is called with the parameter
     "LOC_WONLY".

     "loc_size" specifies the maximum number of bytes to use when the
     locator is an input target to an SQL statement. It specifies the number
     of bytes returned if the locator is an output target.  If "loc_loctype"
     is LOCFILE or LOCUSER, it can be set to -1 to indicate transfer until
     end-of-file.

     "loc_indicator" is set by the user to -1 to indicate a NULL blob.  It
     will be  set to -1 if a NULL blob is retrieved.  If the blob to be
     retrieved will not fit in the space provided, the indicator contains
     the size of the blob.

     "loc_status" is the status return of locator operations.

     "loc_type" is the "blob" type (SQLTEXT, SQLBYTES, ...).

     "loc_user_env" is a pointer for the user's private use. It is neither
     set nor examined by the system.  "loc_user_env" as well as the
     "loc_union" fieds may be used by user supplied routines to store and
     communicate information.}

  Tlc_mem = record                                // case LOCMEMORY
    lc_bufsize: int4;                             // USER: buffer size
    lc_buffer: PChar;                             // USER: memory buffer to use
    lc_currdata_p: PChar;                         // INTERNAL: current memory buffer
    lc_mflags: mint;                              // USER/INTERNAL: memory flags (see below)
  end;

  Tlc_file = record                               // cases L0CFNAME & LOCFILE
    lc_fname: PChar;                              // USER: file name
    lc_mode: mint;                                // USER: perm. bits used if creating
    lc_fd: mint;                                  // USER: os file descriptior
    lc_position: int4;                            // INTERNAL: seek position
  end;


  //* mint ( *loc_open)();
  Tloc_open = function: mint;

  //* mint ( *loc_close)();
  Tloc_close = function: mint;

  //* mint ( *loc_read)();
  Tloc_read = function: mint;

  //* mint ( *loc_write)();
  Tloc_write = function: mint;


  TTag_Loc = record
    loc_loctype: int2;                            // USER: type of locator - see below

    lc_union: record                              // variant on 'loc'
      case SmallInt of
        0: (lc_mem: Tlc_mem);                     // case LOCMEMORY
        1: (lc_file: Tlc_file);                   // cases L0CFNAME & LOCFILE
    end;

    loc_indicator: int4;                          // USER SYSTEM: indicator
    loc_type: int4;                               // USER SYSTEM: type of blob
    loc_size: int4;                               // USER SYSTEM: num bytes in blob or -1
    loc_status: mint;                             // SYSTEM: status return of locator ops
    loc_user_env: PChar;                          // USER: for the user's PRIVATE use
    loc_xfercount: int4;                          // INTERNAL/SYSTEM: Transfer count

    loc_open: Tloc_open;
    loc_close: Tloc_close;
    loc_read: Tloc_read;
    loc_write: Tloc_write;

    loc_oflags: mint;                             // USER/INTERNAL: see flag definitions below
  end;
  PLoc = ^TLoc;
  TLoc = TTag_Loc;

    //******************************************************************************
    //  ifx_lo_create_spec_t:
    //
    //  This is an opaque structure used for creating smartblobs. The
    //  user may examin and/or set certain fields herein by using
    //  ifx_lo_spec[set|get]_* accessor functions. Prototypes for these acessors
    //  are in incl/sqlhdr.h
    //
    //******************************************************************************

  PPIfx_lo_create_spec = ^PIfx_lo_create_spec;
  PIfx_lo_create_spec = ^TIfx_lo_create_spec;
  TIfx_lo_create_spec = ifx_lo_create_spec_s;



  //******************************************************************************
  // ifx_lo_t: A dummy opaque representation of the smartblob structure
  //
  // This can be used for stack or in-line structure declarations.
  //
  //******************************************************************************

  ifx_lo_ts = record
    dummy: array[0..SB_LOCSIZE] of Char;
  end;

  PIfx_lo = ^TIfx_lo;
  TIfx_lo = ifx_lo_ts;


  //****************************************************************************
  { ifx_lo_stat:

   This is an opaque structure used in querying attribtes of smartblobs. The
   user may examin fields herein by using ifx_lo_stat_* accessor functions.
   Prototypes for these acessors are in incl/sqlhdr.h

   The accessors are defined as follows:
       ifx_lo_stat_size: contains the size of the LO in bytes.
       ifx_lo_stat_uid: reserved for future use: the user id for the
           owner of the LO.
       ifx_lo_stat_atime: the time of last access. This is only maintained if
           the LO_KEEP_LASTACCESS_TIME flag is set for the LO.
           Resolution is seconds.
       ifx_lo_stat_mtime: the time of last modification. Resolution is
           seconds.
       ifx_lo_stat_ctime: the time of the last status change (this includes
           updates, changes in ownership, and changes to the number of
           references).  Resolution is seconds. See Appendix B2.11,
           Future Embedded- language feature issues, Smartblob API
           functions using lofd, for enhancements that extend support
           for named and external LOs.
       ifx_lo_stat_refcnt: the number of pointers to this LO - when 0 the LO is
           typically deleted. See deletion criteria.
       ifx_lo_stat_cspec: a pointer to the opaque create spec for this object.
           (see ifx_lo_spec[get|set]_ accessors for details.)
       ifx_lo_stat_type: the 8 byte code for the LO's type}

  //****************************************************************************

  PPIfx_lo_stat = ^PIfx_lo_stat;
  PIfx_lo_stat = ^TIfx_lo_stat;
  TIfx_lo_stat = ifx_lo_stat_s;


implementation

end.